Next: Simple Packages, Up: Packaging [Contents][Index]
A package is either a simple package or a multi-file package. A simple package is stored in a package archive as a single Emacs Lisp file, while a multi-file package is stored as a tar file (containing multiple Lisp files, and possibly non-Lisp files such as a manual).
In ordinary usage, the difference between simple packages and multi-file packages is relatively unimportant; the Package Menu interface makes no distinction between them. However, the procedure for creating them differs, as explained in the following sections.
Each package (whether simple or multi-file) has certain attributes:
A short word (e.g., ‘auctex’). This is usually also the symbol prefix used in the program (see Coding Conventions).
A version number, in a form that the function
version-to-list understands (e.g.,
‘11.86’). Each release of a package
should be accompanied by an increase in the version
number.
This is shown when the package is listed in the Package Menu. It should occupy a single line, ideally in 36 characters or less.
This is shown in the buffer created by C-h P
(describe-package), following the
package’s brief description and installation status. It
normally spans multiple lines, and should fully describe the
package’s capabilities and how to begin using it once
it is installed.
A list of other packages (possibly including minimal acceptable version numbers) on which this package depends. The list may be empty, meaning this package has no dependencies. Otherwise, installing this package also automatically installs its dependencies; if any dependency cannot be found, the package cannot be installed.
Installing a package, either via the command
package-install-file, or via the Package Menu,
creates a subdirectory of package-user-dir named
name-version, where
name is the package’s name and
version its version (e.g.,
~/.emacs.d/elpa/auctex-11.86/). We call this the
package’s content directory. It is where Emacs
puts the package’s contents (the single Lisp file for a
simple package, or the files extracted from a multi-file
package).
Emacs then searches every Lisp file in the content directory
for autoload magic comments (see Autoload). These autoload
definitions are saved to a file named
name-autoloads.el in the content
directory. They are typically used to autoload the principal user
commands defined in the package, but they can also perform other
tasks, such as adding an element to auto-mode-alist
(see Auto Major
Mode). Note that a package typically does not
autoload every function and variable defined within it—only
the handful of commands typically called to begin using the
package. Emacs then byte-compiles every Lisp file in the
package.
After installation, the installed package is loaded:
Emacs adds the package’s content directory to
load-path, and evaluates the autoload definitions in
name-autoloads.el.
Whenever Emacs starts up, it automatically calls the function
package-initialize to load installed packages. This
is done after loading the init file and abbrev file (if any) and
before running after-init-hook (see Startup Summary).
Automatic package loading is disabled if the user option
package-enable-at-startup is nil.
This function initializes Emacs’ internal record of
which packages are installed, and loads them. The user option
package-load-list specifies which packages to
load; by default, all installed packages are loaded. If
called during startup, this function also sets
package-enable-at-startup to nil,
to avoid accidentally loading the packages twice. See
Package Installation in The GNU Emacs
Manual.
The optional argument no-activate, if
non-nil, causes Emacs to update its record of
installed packages without actually loading them; it is for
internal use only.
Next: Simple Packages, Up: Packaging [Contents][Index]